package ch.jamme.conf;

/**
 * Defines a strategy to how a field name should be translated in the corresponding name marshalled into the xml
 * and vice versa. It can be useful to make the produced XML more readable allowing to use a naming convention 
 * that better matches the names of a specific domain. It is also possible to use it when the name of a given field 
 * get changed after a refactor, in order to not lose the backward compatibility of an XML produced before the refactor itself.
 * @author Mario Fusco
 */
public interface FieldNamingStrategy {

	/**
	 * Translates the field name in a given class in the name that should be printed in the generated xml
	 * If the translation direction is an unmarshalling (toXml == false) the MarshallerEngine tries to perform
	 * the unmarshall operation in a best effort way. This means that if it can't find a value in the xml for
	 * the translated field name, it also tries to use the original one. 
	 * @param containingClass The class containing the field
	 * @param fieldName The name of the field
	 * @param toXml States the direction of this translation. True if the translation is from an object to
	 * 				xml (marshalling), false in the opposite direction (unmarshalling)
	 * @return The translated field name to be used in the generated xml
	 */
	String translate(Class<?> containingClass, String fieldName, boolean toXml);
}
